stspeck unexpected behaviour with widget click - #8

Added images to README

Major infrastructure upgrade to modern JupyterLab 3+ and ipywidgets 8.x

## What's New

- Modern JupyterLab 3+ federated extension system
- ipywidgets 8.x support with backward compatibility for 7.x
- TypeScript-based widget implementation with Webpack 5
- Automatic installation (no manual labextension install needed)
- Updated build system with hatchling and hatch-jupyter-builder

## Breaking Changes

- Minimum Python version: 3.9+
- Minimum JupyterLab version: 3.0+
- For older environments, use ipyspeck<0.7

## Documentation

- Complete README rewrite with version compatibility warnings
- Added CHANGELOG.md
- Created PUBLISHING.md guide for PyPI releases
- Added check_version.py for version consistency

ipyspeck 0.8.0 (jupyter/, was widget/ipyspeck) and the new standalone
stspeck 0.8.0 (streamlit/) share one renderer and viewer in core/.

Rendering:
- Protein and nucleic-acid cartoons; secondary structure from PDB records
  or computed from backbone H-bonds
- Molecular (solvent-excluded) surfaces, optionally transparent with their
  own ambient occlusion
- Specular, glossy and metallic materials (optionally metals only),
  shadows, depth fog, rim light, saturation, highlight roll-off, colored
  and wider outlines
- Highlighting and ghosting of atom selections; pLDDT, chain, rainbow and
  secondary-structure coloring
- Trajectories (multi-frame XYZ, multi-model PDB) and unit cells
- Atom imposters as quads, slope-scaled AO bias, low-discrepancy AO
  directions, size-independent outlines

ipyspeck:
- Every renderer setting is a trait; toolbar with presets, cartoon /
  surface / ligand toggles, views, colors and snapshot
- save_image() and save_animation() (PNG, GIF, MP4), camera sync,
  apply_preset(), loaders for RCSB, AlphaFold, ASE, RDKit and pymatgen
- Works on Notebook 6 and JupyterLab 3/4 with ipywidgets 7 and 8, and on
  Python 3.8+
- Fixes: rendering on ipywidgets 7, Classic Notebook loading, live trait
  updates, WebGL context leaks, zoom drift in wide viewers

stspeck:
- Standalone Streamlit component with the same settings, toolbar,
  high-resolution PNG download and optional state return; replaces the
  old ipyspeck.stspeck (now a forwarding shim)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Speck is the original renderer by wwwtyro; the banner now names ipyspeck
(with stspeck) and credits Speck.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

ipyspeck 0.8.1 and stspeck 0.8.1.

- Macro-lens depth of field: blur grows with the distance to the focal
  plane in Angstrom and with zoom; 128-tap golden-angle bokeh with
  per-pixel rotation, no bleeding of sharp objects, highlight bloom;
  dofStrength up to 3
- dofFocus: keep an atom selection in focus as the view rotates
- Fix: peptide-like ligands (e.g. saquinavir) were classified as protein
  and hidden in cartoon mode; HETATM residues are polymer only when
  bonded into the chain
- README gallery of 32 renders (media/gallery); banner credits Speck

Tested on Notebook 6 and JupyterLab 3/4 with ipywidgets 7 and 8, and
Streamlit 1.40-1.64, on Python 3.8, 3.9 and 3.10.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

site/ builds the shared viewer (core/) and a live demo into docs/ for
GitHub Pages: load any PDB ID or AlphaFold model, presets, cartoon /
surface / ligand toggles, lighting, materials, macro depth of field,
PNG export, the gallery, and a React example (react.html). The root
README links to it and still credits the original Speck demo.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

- jupyter/example/gallery: one notebook per gallery image (32), each
  reproducing its image with the same settings and camera, plus an index
- Demo: clicking a gallery image loads that scene (camera fitted to the
  viewer, colors, background); ?example=<name> links; only the latest
  load is shown
- Root README rewritten for the current repository (packages, live demo,
  gallery, layout, compatibility, development, credits)
- License: BSD-3-Clause for ipyspeck, stspeck and this repository; Speck's
  original public-domain notice kept as LICENSE-SPECK

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

- Tap to focus: toolbar focus mode (or Alt-click) picks the exact depth under the cursor as the focal plane
- Depth-of-field toggle; looks menu (default, matte, glossy, toon, cover, metal, glass); color menu for
  cartoon, surface and atom palettes; style buttons now change geometry only
- Auto-rotate (autoRotate): fully shaded spinning frames with AO directions fixed to the molecule
- colorScheme and atomColors settings, usable before display; setAtomsColor/setColorSchema use them
- Touch (rotate, pinch zoom, pan), keyboard navigation and labelled, accessible toolbar and menus
- New view-cube and focus icons; demo site shows the version and shares the looks with the toolbar
- Gallery notebooks use atomColors

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…e and cutaway

Formats and data
- mmCIF (PDBx) reader matching the PDB reader atom for atom; SDF / MOL (V2000, V3000) with bonds;
  format detection, .gz files; bonds from CONECT, _struct_conn and Molfile tables always drawn
- from_pdb_id / fetch_pdb download mmCIF; biological assemblies (assembly=1); MD trajectories
  (from_mdtraj, from_mdanalysis, set_trajectory) as binary coordinates; from_rdkit keeps its bonds
- Stale frontend warning when Jupyter serves another ipyspeck version

Large structures
- Instanced atoms and bonds as triangle strips, grid-based bonds in typed arrays, AO budget per
  frame, coarser cartoons for huge complexes, parsing in a Web Worker, gzipped binary transfer,
  exports reuse the viewer's context, GPU buffers and textures released; a 237k-atom ribosome
  renders at 60 fps
- Loading panel listing each step as it runs; settings changes rebuild once per frame

Looks
- Studio floor (floor, floorReflection), Goodsell illustration style, palettes and entity / type
  coloring, atomColor, outlineMode, water, cutaway with plane axis and cut light
- Toolbar buttons for cutaway and the studio floor; looks reset everything they set

Demo site
- Accordion sidebar with every setting, background presets and vignette, reset all / per section,
  copy as Python; gallery of 41 scenes with notebooks (ribosome, capsids, floor, Goodsell, cutaway)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

A film is a list of shots (turntable, rock, orbit, zoom, fly_to, home,
rack_focus, cut_open, fade, crossfade, trajectory, title, keyframes,
together) compiled into a timeline (core/src/film.js). The viewer
previews it with a player bar (core/src/cinema.ts) and renders every
frame fully shaded, with ambient occlusion fixed to the molecule so
nothing flickers; frames are encoded as H.264 with WebCodecs and muxed
into MP4 in the browser (core/src/video.js, core/src/mp4.js).

- ipyspeck: shots module, Speck.preview / stop_preview / save_video /
  keyframe; MP4 comes back in chunks, other formats as PNG frames
- stspeck: film= plays in the component; its download button saves MP4
- Trajectory frames interpolate for smooth MD playback
- Demo site: Animate section with ready-made films and MP4 export

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Videos by name (spin, rock, orbit, tour, focus, reveal, trajectory,
showcase; core/src/recipes.js) adapt to the structure: they find the
largest ligand or the trajectory, and fly_to(face=True) turns a ligand
toward the viewer so it is not seen through the protein.

- Viewer: a clapperboard button lists the videos that fit the structure
  and the size; the player has a labeled Save video button, and a notice
  says when the file is saved
- ipyspeck: save_video('movie.mp4') alone makes a spin; recipes take
  seconds, target, title, subtitle and quality ('draft', 'good', 'best');
  the call says what happens next; errors say what to try instead
- stspeck: film='tour' or shots.video(...); example/video_app.py
- Six notebooks in jupyter/example/videos, from a first video in three
  steps to your own storyboard; preview GIFs in media/videos
- Demo site: one-click video examples, a looping preview of each video,
  and a Videos section
- Default bitrate about 0.12 bits per pixel (7.5 Mbit/s at 1080p30)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…maged files

- Requests from Python that arrive before the viewer exists or has
  loaded wait for it (model-level queue + viewer.whenLoaded()), so
  display(w); w.save_video(...) in one cell works; exports are answered
  by the first view only
- Exports whose shape differs from the viewer keep what is on screen
  (matchFraming): a zoomed-in view is kept with margins; a view showing
  the whole structure is refitted as before; also for PNGs
- Loading a structure cancels a video export with a message; each frame
  checks the structure is still the same
- formats.parse drops atoms with non-finite coordinates (and their bonds
  and frames) instead of letting one NaN blank the structure; the viewer
  shows a notice, and 'No atoms found' for files without atoms
- GIFs default to 480p / 15 fps; ipyspeck[video] extra
- Still crossfades render each picture once; rack_focus(seconds=0)
  turns depth of field on

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…indexed meshes

- Render targets cover the canvas, not a square of its longest side;
  shaders take a 2D resolution and a frame scale (same pixels as before)
- Context without multisampling, depth or stencil (drawing goes to textures)
- Translucent-surface and shadow layers are created only when used
- Nothing is drawn once the picture has converged, nor while the viewer is
  out of sight (IntersectionObserver); exports and snapshots force a draw
- Accumulators ping-pong and are cleared with gl.clear (no texImage2D per
  reset, no copyTexImage2D per AO sample); FXAA ping-pongs too
- AO and shadow depth passes mask color writes (depth-only mode)
- Per-sample camera copy instead of a JSON clone of the view; programs
  switch only when needed; unchanged scalar uniforms are skipped; vertex
  array objects when available
- Surfaces and cartoons are indexed, with byte normals and colors
- Depth-of-field taps follow the blur size
- GPU resets are recovered (webglcontextlost / restored); webgl.js is strict
  and the window.gl debug global is gone

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- Camera button opens a menu: size (viewer's shape at 3000 px, largest,
  1080p, 4K, square, portrait 4:5, vertical 9:16), quality (draft, good,
  best) and background, then Save; IMAGE_SIZES / IMAGE_QUALITY in core,
  renderImage accepts size and quality names
- save_image(size=, quality=) in ipyspeck; export_size / export_quality in
  stspeck, whose camera button now uses the same menu
- Demo: Save an image panel next to Make a video, in Copy as Python
- 'showcase' is kept out of the video menus (menu: false); the demo's GFP
  example is a film written for GFP's chromophore instead

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- The sidebar keeps model settings only: Make a video, Save an image and
  Copy as Python move to an Export menu in the header (image and video open
  the viewer's own menus; Python shows in a panel with Copy)
- Video menu: Text (none or title + subtitle), length, quality, frame rate
  and size; image menu: Text and the page's background
  (host.paintImageBackground)
- save_image(title=, subtitle=); video examples are clickable clips below
  the viewer, each rendered from its own structure

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

- shots.visit(selection, seconds, title, subtitle, width, color): a stop
  on a tour (fly to a site facing the viewer, color it, caption it,
  focus on it, swing around it)
- Highlighted sites of at most 40 residues show their side chains over
  the cartoon
- fly_to(width=) shows a set width in Angstrom
- Notebook 07: a one-minute tour of ABL kinase with imatinib from a list
  of stops; preview GIF and video in media/videos, shown in the READMEs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Videos: ready-made films by name, a clapperboard menu in the viewer, a
player with Save video, flicker-free MP4 made in the browser, shots and
keyframes for your own films, guided tours with shots.visit, and
step-by-step notebooks. Images: sizes, qualities, backgrounds and titles
in the camera menu and save_image. Rendering: 60 - 70 % less GPU memory,
no GPU work when idle or off screen, faster ambient occlusion, recovery
after a GPU reset. Downloads time out with clear messages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>